--  ---------------------------------------------------------------------------
--  @File: file_tools.ads
--
--  @Project: LiberAda
--  @Version: 1.0
--  @Created: 2009-09-23
--  @Author:  Markus Knau�
--
--  @Description:
--    Provides convenience functions for working with the file system.
--  @Usage:
--    This package adds functions to the (@see Ada.Directories) package.
--    File and directory names in this implementation are always full
--    (@see Ada.Directories.Full_Name). Files are always Ordinary_Files
--    and directories are Directory (@see Ada.Directories.File_Type).
--
--  @Modifications:
--    +2009-09-23 MK: Initial release
with Ada.Strings.Unbounded;

package File_Tools is

   --  ------------------------------------------------------------------------
   --  @Type: Files_Type
   --  @Purpose:
   --    Used for returning an array of file names that are found in a
   --    directory (@see Files_In_Directory).
   type Files_Type is array (Natural range <>)
     of Ada.Strings.Unbounded.Unbounded_String;

   --  ------------------------------------------------------------------------
   --  @Function: Is_Directory
   --  @Description:
   --    Determines if the given name is a directory in the file system.
   --  @Parameter:
   --    +Name: to check if it's a directory
   --  @Return:
   --    True if name is a directory otherwise false.
   function Is_Directory (Name : in String) return Boolean;

   --  ------------------------------------------------------------------------
   --  @Function: Is_File
   --  @Description:
   --    Determines if the given name is a file in the file system.
   --  @Parameter:
   --    +Name: to check if it's a file
   --  @Return:
   --    True if name is a file otherwise false.
   function Is_File (Name : in String) return Boolean;

   --  ------------------------------------------------------------------------
   --  @Function: Files_In_Directory
   --  @Description:
   --    Scans a directory and returns the names of all files that are
   --    contained in the directory. If recursive mode is set the names
   --    of files of contained sub-directories are returned too.
   --  @Parameter:
   --    +Directory: to scan for files and directories
   --    +Recurse: if the search should proceed recursively through all
   --      sub-directories.
   --  @Return:
   --    List of names of files and directories found.
   function Files_In_Directory
     (Directory : in String;
      Recurse   : in Boolean := False)
      return Files_Type;

   --  ------------------------------------------------------------------------
   --  @Function: Extract_Filename
   --  @Description:
   --    The name of an ada source file is extracted from a given path to this
   --    file. Example: "/Users/admin/Code/hello_world.adb" => "hello_world"
   --    If requested, the extension of the file is included in the name.
   --    Example: "/Users/admin/Code/hello_world.adb" => "hello_world_adb"
   --  @Parameter:
   --    +Path: The path (including file name and extension) to the source file
   --    +Include_Extension: Defines, whether to include the file's extension
   --    +Ext_Divider: The string that is used to divide the extension from
   --      the file name.
   --  @Return:
   --    The name of the file and (if set) its extension (separated with the
   --    defined extension)
   function Extract_Filename
     (Path : in String;
      Include_Extension : Boolean := False;
      Ext_Divider       : String := "_")
      return String;

   --  -----------------------------------------------------------------------
   --  @Function: Extract_Filename
   --  @Description: Same as above, but with unbounded strings
   --  @Parameter:
   --    +Path: The path (including file name and extension) to the source file
   --    +Include_Extension: Defines, whether to include the file's extension
   --    +Ext_Divider: The string that is used to divide the extension from
   --      the file name.
   --  @Return:
   --    The name of the file and (if set) its extension (separated with the
   --    defined extension)
   function Extract_Filename
     (Path : in Ada.Strings.Unbounded.Unbounded_String;
      Include_Extension : Boolean := False;
      Ext_Divider       : String := "_")
      return Ada.Strings.Unbounded.Unbounded_String;

end File_Tools;
